STOS Falcon Extension

# My STOS Falcon extension

## Instructions for the Falcon Extension (v1.4)

### Contents

- Introduction.
  - Introduction.
  - Getting STOS to run on the Falcon.
  - Registering this software.
  - Frequently Asked Questions.
- Command descriptions :-
  - General
    - cache
    - cookie
    - falc help
    - jagpad
    - lfalc help
    - monitor
    - os version
    - set cache
  - Graphics
    - cycle
    - df video
    - falc bar
    - falc box
    - falc cls
    - falc colour
    - falc draw
    - falc ink
    - falc mkey
    - falc mouse off
    - falc mouse on
    - falc plot
    - falc set mouse
    - falc set zone
    - falc x mouse
    - falc y mouse
    - falc zone
    - fpal
    - gdos font
    - goraud
    - init goraud
    - init virtual
    - planes
    - quick fade
    - scrsize
    - set fpal
    - set fv
    - set video
    - st compat
    - tc collide
    - tc copy
    - tc effect
    - tc fade
    - tc point
    - tc scrn fade
    - tc sprite
    - tc text
    - tga encode
    - tga decode
    - tga height
    - tga width
    - virtual
    - xres
    - yres
  - Sound
    - dsp clear
    - dsp play
    - dsp process
    - dsp stop
    - dtm inst
    - dtm name
    - dtm play
    - dtm stop
    - dtm voices
    - falc freq
    - falc mic thru
    - falc sammde
    - falc sam play
    - falc sample
    - falc sampos
    - falc samstop
    - set gain / lgain / rgain
    - set volume / lvolume / rvolume
    - speaker on/off
    - tracker inst
    - tracker name
- Commands in progress.
- Version history.
- Credits.

### Introduction

This extension has been written to allow STOS to take advantage of the new facilities provided by the Atari Falcon. The current version only touches on some areas of the Falcons abilities very lightly (such as DSP Processing - this is available, but only if you can code DSP assembler). Future versions will hopefully go even further, making programming the Falcon easier, without the need to resort to coding in assembler, or C.

To install the extension, simply copy the files FGRAPHIC.EXX and FAUDIO.EXY into the STOS folder, and FGRAPHIC.ECX, FAUDIO.EXY into the compiler directory.

When STOS initializes the graphics extension, it will select the correct Falcon resolution, so that STOS goes to a ST compatible screen rez, whatever you were in before running STOS. The initial resolution is not restored upon exit. In a screen mode where the vertical resolution is >=400 ST High will be chosen. Otherwise, ST Medium will be set. This will only be done on TOS 4 and above.

This extension is SHAREWARE, so if you like it (or use it!!) then you should send me some money... See below for details.

### Getting STOS to run on the Falcon.

Due to the way that STOS was originally written, STOS does not work correctly on the Falcon without patching. Even with patching, not all of the bugs can be removed. Some of the problems encountered are listed below, along with a sollution.

- Problem: The mouse does not respond.
  Solution: Use my new loader program - BASIC207.TOS.
- Problem: The joysticks do not work.
  Solution: Use my new loader program.
- Problem: The keyclick goes wild.
  Solution: Use a different STOS loader (not BASICMJH.PRG).
- Problem: Graphics functions dont work.
  Solution: Un-patched. Use graphics functions from an extension. (This one?)
  Also, use my new loader, as this improves the compatibility.
- Problem: Computer crashes apon quiting.
  Solution: Use my new loader program.
- Problem: Change mouse to user defined doesn't work.
  Solution: Un-patched. Use sprite x mouse,y mouse.
- Problem: Palettes are not correctly set.
  Solution: try SET FPAL in this extension.....
- Problem: Running STOS from >= 400 vertical resolution mode does not work.
  Solution: Use my new loader program. (spotted the pattern yet? :)
- Problem: The screen-mode is not changed when running.
  Solution: Do you have NVDI installed? If so remove it.

As you can see, I have patched the loader program to STOS so that most of the problems with STOS are cured. The version included with this extension is only a beta version as there are still problems with it, although I am working on these.

I have also written a Generic STOS Fixer, which fixes a STOS program for up to 10 OS versions, which is useful for fixing old STOS programs which you do not have the source code to. It is FREEWARE, and is available from the usual FTP sites and PD libraries.

STOS, will not run under MultiTOS, so dont bother trying.... I have found, however, that compiled versions sometimes work...(to some extent) give 'em a go!

For more information about running STOS on a Falcon (or any non-ST) see the documentation to the Generic STOS Fixer, and to Basic207

### Registering.

This extension is shareware, and so, if you like it/use it, you owe me some money! As we all know, students are not the richest of people, so I can assure you that I could certainly use some cash...

I am only asking for 5 pounds (sterling), so it's not much.... (infact, some have said its too little!! - your welcome to send more ;>)

If you register, you get a the latest version, along with a compiler that does not display the fact that you have not registered before running your program. I will also send you some example source code showing how to use some of the commands.

Registered users may write to me, with questions/requests and I will do my best to answer them. If you have internet access, I can send you all of the above via email (during the academic year), along with regular updates, if you want them... Registered users without internet access are welcome to contact me to get updates - simply send me a disk, and I'll send it back with the latest version.

If you dont feel that this extension is worth 5 pounds, write to me, telling me what is wrong with it (eg. commands/bugs etc), and I will try to fix it...

To register, simply send me 5 UK pounds (cheques payable to Anthony Jacques) at:

STOS Falcon Extension registrations,
70 West Avenue,
Oldfield Park,
Bath,
Avon.
BA2 3QD
ENGLAND

During the term-time of 96/97, I can be reached at:

Sycamore 38
Oak House
Whitworth Lane
Manchester
ENGLAND

Both addresses will reach me, but the Bath address may take longer during the accademic year, as it will be redirected by my parents. It should be noted that the Manchester address is ONLY for the accademic year - over holidays, mail will not be read/re-directed.

#### WARNING:

This extension will soon be obsolete - I am working on another extension, called 'Falcon Missing Link' which will provide all the facilities that TML does for ST's for the Falcon. This will be shareware with a registration fee of 10/15 pounds. Registered users of this extension will be sent this new extension for free, if/when it is completed.

### Frequently Asked Questions.

In this section, I shall answer some frequently asked questions about the extension. If you are having trouble, consult this section first, and if the answer to you question is not here, then email me...

- - When I change screenmode, all I see is a load of rubbish - why?
  - As STOS does not support Falcon resolutions, any graphics drawn by STOS will look corrupted when you switch to a Falcon mode. The way to solve this is to reserve a bank that is big enough to hold a screen of the resolution that you want, and to change PHYSIC to the start of this bank. Now you can use PHYSIC as the address for all of my graphics commands (ie FALC CLS) to draw onto the screen.
- - SET VIDEO causes a bus error on my TOS 4.01/2 Falcon. Why?
  - There is a bug in these OS versions, where the OS decides to clear a screen before changing video mode. The screen that it clears is LOGIC, and is of the NEW SIZE. Thus, if LOGIC does not point to a memory bank that is big enough for the new size screen, it will overwrite important data, causing this bus error. Before changing mode ALWAYS set logic to a big enough bank.
- - SET VIDEO clears the screen before changing mode - why is this?
  - This is the same bug as the previous question. for TOS 4.01/2, the operating system decides to clear the screen after changing video mode. I do not know the reason for this - all I can say is that it does not do this under TOS 4.04# so be aware of this.
- - I have heard about another extension, by Anthony Hoskin. Is it compatible?
  - Yes and no. Unfortunately, we have both chosen to use the same letters for our extensions. If you rename them, you can have them both installed at the same time. The graphics commands are, at this time, incompatible (although I am working on that...). The audio commands are compatible though, from the testing that I have done...
- - Can this extension really be used to write full games?
  - Yes! Although the extension currently only has a small number of sprite commands, it is possible to write a game, running in true-colour using only this extension and STOS (and Spooky Sprites). I know of two games already in the pipeline, and another 99% finished.

### Command descriptions.

Following is a list of the instructions/functions, and what they do.

Some of these instructions assume a Falcon. If a falcon specific instruction is called on an ST, I do not know what will happen. (I would guess a bus error or illegal instruction). The user should test what machine the program is running on first (either using os version, or cookie).

### General

#### x=cache

This function returns the current state of the '030 instruction and data caches. The result is represented by a sequence of bits. They are encoded in in the same way as in SET CACHE.

#### x=cookie(cook)

This function returns the value of the given cookie. If there is no cookie jar, or the cookie is not found, it returns a "Not Found" error.

eg.
`10 print cookie("_MCH")`

will print the value of the _MCH (machine) cookie. On a TOS 1.0 FM this will give the error message "Not Found in line 10."

A list of cookie ID's and the ascoiated meanings can be found on the WWW (email me for an address). The Atari cookies are also listed in Hisofts Modern Atari System Software - Appendix C.

#### falc help

This instruction displays on screen the syntax of each command available in this extension. This is designed to make it easier to use the commands.

As this is intended for editor use, this instruction cannot be compiled.

#### x=jagpad(port)

This function returns a binary value giving the state of each of the 21 keys on a Jaguar controller connected the the extended controller port PORT (0-1) The value returned allows the programmer to detect any combination of keys.

The bitwise representation of this value is :-

1 4 7 * 3 6 9 # 2 5 8 0 o p c b a r l d u

Where o = option, p = pause, a/b/c = fire buttons r/l/d/u=directions, and the others are keys on the "phone pad".

Each bit can be tested by anding with the bitwise value
ie
`10 x=jagpad(0) : if (x and %10) then down
20 if (x and %1) then up`

Anyone who has heard about Bad Mood, the Falcon Doom clone may be interested to know that the Jaguar control pad code used in this is the same code as this command...

#### lfalc help

This instruction sends the help screen that is displayed by FALC HELP to the printer. This should be used if you do not intend to print out this manual.

As this is intended for editor use, this instruction cannot be compiled.

#### x=monitor

This returns the monitor type that is currently connected.

The form of x is :-
0 = ST mono monitor
1 = ST colour monitor
2 = (S)VGA monitor
3 = Television.

There is no method of distinguishing VGA and SVGA monitors. SVGA are capable of a wider range of frequencies and resolutions, but you will have to take the word of the user that their monitor can cope.

#### x=os version

This function returns the OS version. The radix point is not inserted, but is always two digits from the right. (eg. $404 = $4.04)

eg. `10 print hex$(os version)`

#### set cache VALUE

This instruction sets the current state of the cache. VALUE is encoded in the following way:

    x x x x x x x x x x x
    | | | | | | | | | | |__ Enable Intruction cache.
    | | | | | | | | | ----- Freeze instruction cache.
    | | | | | | | | ------- Clear instruction entry.
    | | | | | | | --------- Clear instruction cache.
    | | | | | | ----------- Instruction burst enable.
    | | | | | --- Enable data cache.
    | | | | ----- Freeze data cache.
    | | | ------- Clear data entry.
    | | --------- Clear data cache.
    | ----------- Data burst enable.
    ------ Write allocate

As you can see, it is quite complex. However, for optimum speed, a value of 12561 should be passed.

NOTE: Encoding technique is likely to change (to simply on/off).

### Graphics

#### cycle index,count

This instruction cycles COUNT palette entries starting from INDEX in the Falcons 256 colour palette.

All of the palette handling routines also apply to the NON-ST COMPATABILITY bit-plane based modes (ie. not true colour, or ST comp.)

#### df videl n,h,s,o,p,v,8,c

This instruction defines a video mode N, which can range from 1-9. This mode is defined by the remaining flags. The value of these flags does not matter (with the exception of c) To set a flag, give a non-zero value. The meanings of thes flags are :-

h - vertical height (double line / interlace)
s - ST compatibility mode
o - overscan (enabled)
p - PAL / NTSC (ie set = 50Hz, clear = 60 Hz)
v - VGA mode
8 - set 80 column mode
c - Number of colours. Valid values=2,4,16,256,65536. Other values give 2.

eg.
`df video 1,1,0,0,0,1,0,65536` would set 320x240x65536 on a VGA monitor

Please make ALL programs both VGA and RGB compatible. There is a small enough user base, even without dividing it!!!

NOTE: 640x?x65536 is not a valid mode for a VGA monitor....

#### falc bar col,x1,y1,x2,y1,scr

This instruction draws a filled bar on the screen at address SCR. This screen is assumed to be of the resolution / colour depth as the current one. The co-ordinates of the bar are given by x1,y1,x2,y2 assuming the first pair to be the top left corner, and the second the bottom right.

It is drawn in the current colour.

#### falc box x1,y1,x2,y2,scrn

This instruction draws a hollow box on the screen at address SCR. The screen is assumed to be of the same dimensions/colour depth as the current screen. The top left corner is drawn at the point (x1,y1), and the bottom left corner at the co-ordinates (x2,y2).

It is coloured with the current colour.

#### falc cls scr_address

This instruction clears the screen at the given address. The entire screen (even with a virtual screen) is filled with colour zero. This instruction no longer uses the BLiTTER, so should no longer cause problems with joysticks or other interupt driven routines. It may also be slightly faster.

#### falc colour index,red,green,blue

This instruction sets colour number INDEX in the palette to the colour made up of the components RED,GREEN and BLUE. Each of these can range from 0-63. So, white is defined as 63,63,63.

#### falc draw screen,x1,y1,x2,y2

This instruction will draw a line in the currently selected colour on the screen at address SCREEN from coordinates X1,Y1 to X2,Y2. At the moment, only horizontal and vertical lines will be drawn, and only in true-colour modes. This will change soon...

#### falc ink index

#### falc ink red,green,blue

This instruction sets the current colour for all (my) graphics routines. The value index is the 16-bit colour value when in true-colour mode, otherwise it is the index of the colour in the palette (0-255).

If the three value version is used in true colour mode, then the three values will be combined to make the 16-bit colour from the red,green and blue components. It should be noted that to ensure that the collision bit is not set, an even value should be passed for green.

#### n=falc mkey

This funtion returns the state of the mouse buttons when using the mouse routine from this extension. The value return is encoded in the same way as the equivelent STOS routine - ie : 0=none, 1=left, 2=right, 3=both.

#### falc mouse off

This instruction switches off the Falcon extension mouse command, and restores the STOS mouse routine.

#### falc mouse on

This instruction enables a mouse routine which is able to go beyond the screen size of ST-high. It takes the maximum dimension of the screen from the current dimensions. Thus, if using a 800x600 virtual screen, this is the range of the mouse co-ordinates.

It should be noted, that unlike the STOS mouse routines, a pointer is NOT displayed at the current postition of the screen. If this is desired, tc sprite/tc copy can be used in true-colour mode.

#### falc plot screen,x,y

This instruction plots point (x,y) on screen with the current colour. The routine is faster than the STOS 'PLOT' command, even though it supports 4/16/256 and true-colour modes!!

#### falc set mouse x,y

This instruction sets the current position of the mouse cursor to the coordinates (X,Y) as given.

#### falc set zone n,x1,y1,x2,y2

This instruction defines a zone which can be tested for the presence of the mouse. X1,Y1 is the co-ordinate pair of the top-left corner of the box to be defined. X2,Y2 is the co-ordinates of the bottom right hand corner. N is the number of the zone to be defined, and may range from 0 to 63

.

#### n=falc x mouse

This function returns the x co-ordinate of the mouse pointer when using the mouse routine in this extension.

#### n=falc y mouse

This function returns the y co-ordinate of the mouse pointer when using the mouse routine in this extension.

#### n=falc zone(m)

This function returns whether or not zone number M contains the mouse-pointer or not. The value returned is either TRUE (-1) or FALSE (0)

#### fli do frame SCREEN

This instruction decodes the next frame in an FLI animation. the value SCREEN should be an address of the screen which it is to be decoded to. If it is not the first frame, this screen MUST contain the previous frame in the animation - this is because FLI files only store the differences between frames.

At this time, only FLI and FLC chunk types are supported - although only at a fixed size of 320x200 (other resolutions will be allowed soon...) FLH files will only be implemented when I have the file-spec. of the format. (If you have it, then send it, please...)

#### X=fli frame

This function returns the frame number of the next frame to be decoded in an FLI animation. At the end of the animation, it will return the number of frames + 1.

#### fli init FLI_ADDR

This instruction initialises an FLI animation. FLI_ADDR is the address of the FLI file. This should always be called before attempting to display an FLI frame. At this time, only FLI/FLC files are supported. The true-colour FLH format is not supported yet (but hopefully soon!)

#### fpal adr,index,count

This instruction copies the palette to the memory starting at ADR. INDEX is the number of the first palette to store, and COUNT is the number to store. The data is stored in the same format as SET FPAL.

#### gdos font n,addr

This instruction sets which font will be used by tc text. ADDR holds the address of the font, and N is the number of the font in the data to use (More than once size may be held in one data-block).

Although the routine uses GDOS fonts, currently only the system font is supported. This will change very soon. This routine has been included at this stage as not all OS versions have the font at the same address.

To find the system font in memory, use a memory searcher program (such as MON from devpac) to search for the string "system", as this is in the font name. The data should say "8x8 system font" (or 6x6 or 8x16). This address-4 should be passed to this instruction.

Registered users have a piece of source code which actually searches for the fonts, and returns the relevent addresses... On my TOS 4.04 Falcon the following addresses were found: (addresses as passed to instruction)

- 6x6 - $e4afec
- 8x8 - $e4b6c8 (This address is used by default)
- 8x16- $e4d124

#### goraud scr,col,x1,y1,i1,x2,y2,i2,x3,y3,i3

This instruction draws a goraud shaded triangle on a true colour screen at address SCR. x1-x3 and y1-y3 are the co-ordinates of each of the three corners. i1-i3 are the relative inensities of the three points. This may range from 0 to $7fff.

The corners should be specified in a clock-wise direction.

COL determines the colour. The valid values are :-
0 - Red
1 - Green
2 - White
3 - Brown/orange

If the colour is anything other than these, it will be assumed to be the address of the colour table. The colour table consists of 32 words, each a true colour value. word no. 0 is the darkest and word no. 31 the brightest. This must be followed by 16 empty words.

NOTE: CANNOT BE COMPILED.

#### init goraud

This instruction sets up various parameters for the Goraud routine (see above). This MUST be called before goraud.

NOTE: CANNOT BE COMPILED.

#### init virtual xres,yres

This command initialises a virtual screen of dimensions XRES by YRES. The actual resolution of the screen / number of colours is determined by the current screenmode. Calling `setvideo 0` will restore the screen.

#### x=planes

This function returns the number of bit-planes in the current screenmode. The values returned are 1,2,4,8 and 16.

#### x=quick fade(colour)

This function fades a 256 colour palette to the given colour. The colour is stored as a 18-bit number, where the top 6 bits represent the Red component, the next 6 are the Green component, and the bottom 6 bits are the Blue component.

The returned value, x is the number of palette entries changed.

NOTE: There seems to be some inteference at the top of the screen ?!?

#### x=scrsze(videomode)

This function returns the amount of memory taken for a given screenmode. The value VIDEOMODE is the number (0-9) of the defined video mode.

This function does not take account of any virtual screen, or expanded screen (using `set fv`)

#### set fpal addr,index,count

This instruction sets the Falcons 256 colour palette. ADDR stores the address at which the first palette entry is held. INDEX stores the first register to change, and count is the number of colour registers to change.

The data is stored longwords in the XRGB format of the XBIOS. An array can be used to hold the palette data, with the address passed using varptr.

eg.
`set fpal VARPTR(MYPAL(0)),0,256`

#### set fv addr

This command allows the use of non-standard screen resolutions by setting the video registers to those specified in a FV (version 2) file. The address of the start of this file is passed in the parameter ADDR.

Note that FV files are, by their very nature, dangerous, as setting the registers to incorrect values could be harmful to your monitor. I take no responsibility for any problems caused by using this command. Having said this I have synced my SVGA up to 100Hz, and have had no adverse effects...

#### set video n

This instruction sets the video mode to a previously defined mode. N may range from 0-9. Video mode 0 is set to the video mode which is chosen at boot-up of STOS (ie ST Medium / ST High) - and is changed by the ST COMPAT command to the new default resolution.

On TOS < 4.04, when changing screenmode with this the OS will clear the screen at the current LOGIC address ready for the new screen. If you have not set this to be a bank of sufficient size (ie. reserve as work 1,153600 : physic=start(1) : logic=start(1)) it will quite possibly cause a bus error. If it is essential that the screen isn't cleared, the only alternative is to use the SET FV command.

#### st compat n

This command switches the video mode from one ST screen mode to another. It initialises both this extensions graphics commands, and the STOS routines for the new mode. N may range from 0 to 2, where 0 is ST Low and 2 is ST High.

The command should work on an ST (although cannot switch to ST High).

At this time, it is neccesary to use the DEFAULT command after this instruction as It does not completely re-initalise STOS. I hope to remove this problem.

#### x=tc collide

This function calculates if there has been a collision since this function was last called, and returns a boolean value (TRUE/-1 or FALSE/0) indicating this state.

The collision is pixel-perfect, and determines if any part of the sprite that is drawn collides with something already on screen which has the last green bit set (the bitmap is RRRR RGGG GGGB BBBB, so to set this bit, OR the pixel data with $20)

I am not very happy with this instruction, as setting the G bit is quite tricky as there is no direct support for this in any art-package, or sprite editor. I may at some time write such a utility, however a more likely solution is that I will write a better set of collision detection routines (perhaps simular to those used in the CONTROL extension by Les Greenhalgh).

#### tc copy scr1,x,y,w,h,scr2,x2,y2

This instruction copys a block of width W and Height H from the point (X,Y) on the screen at address SCR1 to the screen at address SCR2, with the top left corner at the point (X2,Y2). This instruction no longer uses the BLiTTER, and so should no longer cause problems when used at the same time as joysticks, and may even be slightly faster. NOTE: Dont pass -ive width and height parameters! I tried this, and it caused my machine to reboot, and trashed the NVRAM !!!!!

#### tc alpha mask

This effect takes 1 parameter - a mask which is used for allowing only certain bits to be affected by sprite commands. The value MASK is a 16-bit value, which indicates which bits of the background colour are overwriten, and which are not. If a bit has a 1, the value of that bit in the sprite is used - a value of 0 causes the backgound pixels bit to be used.

#### x = tc fade(length,address)

This function fades a True Colour screen towards the currently selected colour. The ADDRESS is the start of the screen to fade. LENGTH is the length of the part to fade. (ie the length of 1 screen if the whole screen is to be faded.)

The returned value is the number of pixels that were faded. When this value is zero, the whole screen has be faded to the given colour.

#### z=tc point screen,x,y

This returns the RGB value z, of the pixel on screen at coordinate (x,y) in True Colour mode. This command has the same purpose as the STOS command point.

#### tc scrn fade screen1,screen2,length

This instruction fades one True Colour screen into another. Simply pass the addresses of the screens as parameters, and the length.Both screens must be of the same size.

#### tc sprite x,y,n,scr,spr

This instruction draws a sprite created with Spooky Sprites (by Johan Karlsson - d92jk@efd.lth.se ) in true colour mode. X and Y are the co-ordinates at which to plot the sprite. N is the number of the sprite to draw. SCR is the address of the screen, and SPR is the address of the sprite bank.

Currently, clipping is only supported vertically on UNPACKED sprites. However, further support is on the way...

#### tc text screen,x,y,string$

This instruction will print the string stored in STRING$ on the screen at address SCREEN at coordinates X,Y. It will be printed in the current font (not the STOS one) The text is plotted in the currently set colour, using FALC COLOUR.

Future versions (very soon) will support GDOS fonts, stored at the given address. However, only fonts with the data in motorola format will be supported as I dont want to slow the printing down by supporting both Intel and Motorola formats.

INFO: Motorola / Intel format:
Motorola format is where 2 byte values are stored HIGH BYTE | LOW BYTE. (ie with the bits from left to right decreasing in significance.)

Intel format is where 2 byte values are stored LOW BYTE | HIGH BYTE. Thus, to convert from one format to the other requires that the two bytes are switch order. I will supply a STOS program which will detect whether it is a motorola or intel font, and to convert an intel format one into a motorola. You are free to use it in any program you like to allow all GDOS (not Speedo) fonts to be used by you programs.

#### tga decode tga_addr,dest_addr

This instruction will decode a type 2 targa (.TGA) picture. The targa should be at the address TGA_ADDR, and the destination screen should be at DEST_ADDR. The screen is assumed to be of the correct size for the targa, and is assumed to be a true-colour screen.

To ensure that you reserve enough memory for the decoded picture, the size can be calculated by:

width * height * 2

The source and destination addresses should be different, as corruption will occur in most pictures - only those stored left-to-right and top-to-bottom will not be corrupted by decompressing over the original file.

The decode routine only supports type 2 targas. These are by far the most common type, and are uncompressed true colour images. (15/16/24/32 bit). The routine does however support any of the four orientations in which the picture may be stored.

#### tga encode source,dest,width,height

This instruction creates a 16-bit uncompressed .TGA at the address DEST of the true colour screen of dimensions WIDTH, and HEIGHT starting at address SOURCE. The size of the .TGA can be calculated as: (WIDTH*HEIGHT*2)+18. This is the minimum size which you should reserve for DEST.

#### x=tga height(addr)

This function returns the height in pixels of the targa at ADDR. This is useful for calculating the amount of space required for the picture.

#### x=tga width(addr)

This function returns the width in pixels of the targa at ADDR. This is useful for calculating the amount of space required for the picture.

#### virtual x,y,screen

This command positions the view-port in a virtual screen. The virtual screen should start at SCREEN, and X,Y should be the co-ordinates of the top-left pixel to be displayed on screen.

Currently in bit-plane modes, only screens with X a multiple of 16 will be displayed correctly. In true-colour mode, X must be a multiple of 2.

The virtual screen is achieved through the 'Hardware Scrolling' hardware, and so can be used to implement infinite scrollers...

#### X=xres

This function returns the horizontal resolution in pixels. This includes any virtual screen that is in use, and will take account of unusual modes defined with a .FV file.

#### Y=yres

This function returns the vertical resolution in pixels. This includes any virtual screen that is in use, and will take account of unusual modes defined with a .FV file.

### Sound

#### dsp clear

This command can be used to reset the entire sound sub-system. It does this using the XBIOS call Sndstatus, however, it does not perform exactly as the system call.

The command flushes the DSP of all subroutines, and then tri-states it (disconnecting it from the sound-system). All DSP interupts are disabled, and all conections (not just the DSP) in the sound system are disconected. The sample playback resolution is set to 8-bit stereo, and all DMA transfers are halted.

However, unlike the XBIOS, the gain and attenuation (volume) settings are not cleared, and the PSG and the Matrix are both connected to the audio output.

This command should be used to clear the sound-system if an error occurs, or to remove a DSP routine which has been loaded in (either with TRAP or with the DSP PROCESS command).

All internal flags are cleared, and so, any play routines will not need the corresponding stop. (eg DTM PLAY start(14),155555 : DSP CLEAR would not need a DTM STOP command, as DSP CLEAR would do this.)

#### dsp play modaddress

This instruction plays a 4-track mod file on the DMA sound system using the DSP. This causes little slowdown, unlike other replay routines.

Due to a bug in part of the code (not by me), the file "dspmod.bsw" must be loaded each time a module is played. This file is read by the extension from the current directory. If the file could not be found, the "Not done" error will be returned.

(for those who wish to know why, the code cannot be run twice, as it seems to modify itself {or a variable} causing an illegal instruction.)

modaddress is the address at which the module can be found. If this is a memory bank, it must be specified as start(10), not as 10.

eg.
`10 reserve as work 15,195636 : load "bubleman.mod",15 : dsp play`

#### dsp process file$,buffer,mode

This instruction allows you to process audio data with the DSP. The DSP load file (.LOD) FILE$ is loaded into the dsp with the DSP_LoadProg call. BUFFER should point to an area of space which can be used to process the .LOD file. The size of this area is "3 * (length of program / data words + (3 * no of blocks in program))".

MODE is a value which indicates what you wish to be processed. There are currently 3 modes. These are:

- 0 : Process audio through. Data is passed from the ADC -> DSP -> DAC, and so provides real-time processing.
- 1 : Process audio record. Whenever FALC SAMPLE is called, the data is passed via the DSP, enabling filtering etc. to be performed at record time.
- 2 : Process audio playback, Whenever FALC SAM PLAY is called, the sample is passed through the DSP, enabling effects to be performed on previously recorded data.

A forth mode may be added, which takes a sample in memory, processes it, and places it back in memory. This would allow perminent processing.

Registered users should consult the DSP directory for further details on writing the DSP part of the routines (including example code).

#### dsp stop

This instruction stops the dsp module that currently is playing. If the mod is left playing, and the memory is re-allocated (eg exiting STOS), the code will cause a bus error (probably...)

#### X$=dtm inst (number,addr)

This function returns the name of instrument no. NUMBER in the DTM module at address ADDR. The name is returned in the form of a string. The instrument name is often used to store information about the module, writen by the composer.

eg.

`10 reserve as work 10,355000 : bload "test.dtm",10
20 i$=dtm inst(1,start(10)) : print i$`

will print the name of the first instrument in the DTM module TEST.DTM.

#### x$=dtm name(addr)

This function returns a string containing the name of a DTM module at address ADDR.

eg.

`10 reserve as work 10,355000 : bload"test.dtm",10`

20 i$=dtm name(start(10)) : ? i$

will print the name of the module TEST.DTM

#### dtm play dtmaddr,length

This instruction plays a Digital Tracker Module using the DSP and the Audio sub-system. The address of this module should be passed in the dtmaddr parameter, and also the LENGTH of the file.

When reserveing the space for the module, you must reserve an extra 200000 bytes, as this is used as temporary storage by the player routine.

The current version of the player only supports 8-bit mono samples, and only modules with an even number of voices (up to 32 tracks!!!)

NOTE: CANNOT BE COMPILED

#### dtm stop

This instruction stops a piece of DTM tracker music.

NOTE: CANNOT BE COMPILED

#### X=dtm voices addr

This function returns an the number of voices (or tracks) that the DTM module at address ADDR uses. This command can be used to test that the module uses an even number of tracks, as the current replay routine does not support modules with an odd number of tracks.

#### falc freq value

This instruction selects what frequency should be used for DMA sound (ie for DSP PROCESS, and FALC SAMPLE / SAMPLAY. The change will only take effect when the next command using the DMA is called.

There are 8 different frequencies available. These are coded in the following way:

      1 = 49170 Hz          5 = 16390 Hz
      2 = 32780 Hz          7 = 12292 Hz
      3 = 24585 Hz          9 =  9834 Hz
      4 = 19668 Hz         11 =  8195 Hz

All other values will give a MUTE condition (ie it wont play....).

NOTE: The frequency encoding is likely to change, to allow for 50, 25.5 and 12.5 Khz freqencies also supported by the DMA.

#### Falc mic thru

This instruction toggles the microphone through, and the PSG output. Both are mixed with the output of the matrix (ie DMA/DSP). This can be used to allow the output of an external device such as a walkman through you Falcons speakers.

#### Falc sammde x

This instruction sets the resolution of sample playback. The value X gives the mode. Valid modes are :-

0 - 8 bit stereo
1 - 16 bit stereo
2 - 8 bit mono
This call does not affect recording mode - all recording is done at 16 bit stereo.

#### Falc samplay start,end,loop

Using this command a sample starting at address START and ending at END can be played on the Falcons DMA sound-system. The sample is played at the currently selected frequency.

The value LOOP indicates whether or not the sample should be looped. If the value is zero, the sample will not be looped, otherwise, it will be.

There are 8 different frequencies available. These are coded in the following way:

      1 = 49170 Hz          5 = 16390 Hz
      2 = 32780 Hz          7 = 12292 Hz
      3 = 24585 Hz          9 =  9834 Hz
      4 = 19668 Hz         11 =  8195 Hz

All other values will give a MUTE condition (ie it wont play....).

NOTE: The frequency encoding is likely to change, to allow for 50, 25.5 and 12.5 Khz freqencies also supported by the DMA.

#### Falc sample start,end

This command uses the Falcons 16-bit sampling hardware to record a sample into memory starting at START. END is the end of the record buffer, and the sample will not exceed this buffer. Although it doesn't pass the end, sound can still be heard even when the buffer is full. Stop this with FALC MIC THRU.

The sample is recorded at the current frequency. Remember that all recording is done in 16-bit stereo, whatever mode has been set.

#### X=Falc sampos(mode)

This function returns the address of the current sample being played or recorded. Which is returned is determined by the value MODE. If mode=0, then the record pointer will be returned, otherwise, the playback pointer is returned.

There are two uses for this instruction. One to find the end of a sample.

Eg.
`10 falc samplay strt,end,freq
20 repeat
30 until (falc sampos(0)>end)
40 falc samstop`

This program would stop the sample when it reaches the end.

Or, alternatively, it can be used to find the current samples value.
Eg.
`10 falc sammde 0
20 falc samplay strt,end,freq
30 repeat
40 plot x,100 : x=peek(falc sampos(0)) : plot x,100
50 until (falc sampos(0)>end)
60 falc samstop`

This program would play an 8-bit mono sample, and plot a single point on its waveform. This could be used to constuct an osciliscope display. If the sample is stereo, the right sample comes imedately after the left.

#### Falc samstop

This instruction halts all DMA sound interupts (both record and playback). Note that this does not disconnect the microphone throughput, or stop any PSG based sound.

#### set gain l,r / x=lgain / x=rgain

LGAIN and RGAIN return the left and right input gains. Set gain, sets the left and right gains to L and R. All values range from 0 to 15. Each step is a gain of 1.5 dB.

This is done with the XBIOS command (not using the memory location.)

#### set volume l,r / x=lvolume / x=rvolume

LVOLUME and RVOLUME return the left and right output volumes. Set volume sets the left and right volumes to L and R. All values range from 0 to 15. Each step is a decrease of 1.5 dB.

#### speaker on / speaker off

These two instructions switch on/off the internal speaker.

programs should give the user the choice of having it on/off, since not all users have external speakers, and VGA monitors do not include speakers.

#### X$=tracker inst (number,addr)

Like the command DTM INST, this function returns the name of instrument No. NUMBER in the .MOD module at the address ADDR.

#### tracker name (addr)

This command is similar to DTM NAME, and performs the same task - returning the name of a module at address ADDR, but for a .MOD module. The name is returned in the form of a string, which is never over 20 characters in length.

### Instructions in progress

In the current version of this extension, incomplete instructions are included, as you may know if you use the extension selector by Les Greenhalgh... You are welcome to try and get these to work, but if they are not documented, they are not finished - ie probably do not work...

Eventually, I hope to replace all of the remaining TC commands with a FALC version. This will detect the current screenmode, and draw etc. in the correct way. TC GORAUD may be an exception to this....

comming soon....

- mapping commands.
- bitplane mode sprites.
- .AVR file support.
- optimised bitplane graphics.
- complete falc draw.
- Split graphics extension - getting too big...

### Version history :-

Work for this extension began on 10 December 94 (I think).

V0.1
  First interpreter extension code (ever!!!)
  With instructions - set fv, get fv, cookie and speaker on / off, goraud (not working).
V0.2
  Added gain, attenuation, jagpad (not working), dsp play, dsp stop.
  Installed start-up code.
V0.3
  Removed set fv, get fv.
  Added set videl, videl, monitor, os version.
  Fixed DSP play.
V0.4
  Added tc fde, tc scrn fde, my fde, tc plt, tc pnt, scrsze.
  Fixed start-up for RGB (I think - not tested)
  Changed gain etc. to use XBIOS calls, rather than memory location.
V0.4a
  Fixed scrsze (typo), and added checking to DSP play/stop to prevent errors due to the other not being called ( ie DSP stop with no play) Finally coded jagpad (why did Atari make it so complex?!?)
  Completed quick fade,tc point and tc plot.
V0.5a
  Started cycle, and started falc play.
  Fixed gain/attenuation to accept variables.
  Started DTM play / stop.
  Replaced set l/r atten with set volume.
  Replaced video mode routines
V0.5b
  Complete re-write from v0.3 ish due to source code being wiped.
  Added TC sprite and falc sammde.
  TC FADE/TC SCRN FADE/TC PLOT/TC POINT no longer work....
V0.5c
  Fixed the above (TC) routines.
  Fixed sprite/graphics routines to work with all resolutions.
V0.6
  Fixed start-up for RGB. Fixed DSP play bug.
  Completed goraud / init goraud / dtm play / dtm stop.
  Added TC bar / TC box.
  Started virtual/init virtual.
V0.7
  Added TC copy / set fpal / fpal.
  Completed cycle.
  Changed quick fade to 18-bit parameter, from palette form. Compiler now coming on-line.....
  - TC BOX/TC BAR/TC PLOT/TC POINT/DF VIDEO/SET VIDEO/ OS VERSION/COOKIE/LVOLUME/RVOLUME/SET VOLUME/LGAIN/ RGAIN/SET GAIN/TC FADE/TC SCRN FADE/QUICK FADE/ TC SPRITE/SPEAKER ON/SPEAKER OFF/MONITOR/SAM MODE and SCR SZE all now work compiled.....
V0.8
  Added falc mic thru / falc samplay / falc samstop / falc sampos.
  Added falc sample / set fv
  Added above commands to compiler.
  Added FPAL/SET FPAL/CYCLE to compiler.
  Fixed set video for TOS 4.02 (I HOPE!!!!! - NO. Try again....)
V0.9
  Split extension into 2 parts - due to limit of size.
  Added dtm name, tracker name, dtm voices, dtm inst, tracker inst to both Compiler and Interpreter extensions.
  Fixed goraud for any polygon (not just trianges).
  Added dsp process and dsp clear, falc freq, falc ink
  Fixed dtm play/dsp play clash.
V0.9a
  Fixed a few Compiler bugs.
  Completed falc cls. Finished init virtual/virtual
  Fixed tc box bug.
  Started bitplane mode graphics routines...
V0.9b
  Completed bitplane graphics for 4/16/256 colours.
  Fixed compiler DSP play.
  Added set cache,cache.
  Added st compat
V1.0
  Goraud polygon back to only triangles (so that it actually works!!)
  Added falc colour
  Various bug-fixes
  Example code for registered version available.
  Un-registered compiler extension now has start up message.
  Added falc help and lfalc help.
  Added xres,yres and planes.

V1.0a
  Added tga width, tga height and tga decode.
  Fixed yres
  Fixed falc mouse clipping.
  Falc mouse now compiles.
  Finally fixed setvideo for TOS 4.02 (OS bug...)
  Fixed TC sprite for compiler

V1.1
  Added tc text and tc collide
  Fixed a couple of minor bugs.
  Started tc alpha.
  Started .AVR reading code.
  Started falc draw

V1.1a
  Added gdos font
  Fixed bugs in tc text
  Added collide to compiler
  Falc draw partially implemented
  Made mouse routine more stable in editor

V1.1b Fixed bug in yres calculation (caused bus error in falc cls)
Fixed (?) bug in set fv

V1.1c
  Fixed bug in FALC INK's alternative parameters (compiler only)
  Fixed another bug in set fv - number of planes was not set...

V1.2
  FLI Player code coming on-line...
  Completed TC ALPHA
  improved compatibility with Anthony Hoskin's extension.

V1.2a
  FLI player code now works!
  FLC code included.

V1.2b
  TGA decode bug corrected (15/16-bit pictures decoded wrong)
  TGA ENCODE completed

V1.3
  Lots of playing around, trying to get the compiled mouse to work on an STE.
  Removed the TC COLLIDE command, to increase speed of sprites.
  Added the new TC EFFECT command, with 'none', 'solid', 'alpha', 'scale' and 'fragment'.
  Fixed 'alpha' to work with packed sprites.

V1.4
  Lost all changes since V1.2a. :-(
  Re-fixed bugs in TGA decode, and finished TGA encode again.
  Replaced FALC CLS and TC COPY with non-blitter routines to stop them conflicting with interupts based routines.
  Fixed a bug in the compiler SET VIDEO code.
  Fixed some bugs in SET FV, and added bitplane support to it.
  Updated doc's to reflect my work on the STOS loader.

### Credits :-

- Original true colour sprite routine : Johan Karlsson
- True colour fade : code by Genie! of Network Trash
- Goraud polygon : Griff
- DTM replay code : Jaccard Emmanuel
- DSP tracker code : Bitmaster
- FV file format : Johan Karlsson
- FLI/C playback code based upon code by Hydrasoft...

All the rest is by me (Anthony Jacques)

Cheers to RiCH Davey for testing/suggesting commands, and Les Greenhalgh for the tips on extension writing... and of course, to all registered users...

Back to the STOS page...

Back to the index page...